<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<style type="text/css">
body {
	font-family: Verdana, Arial, sans-serif;
	font-size: 10pt;
}

p {
	margin-left: 2em;
	margin-right: 2em;
}
</style>
<title>JavaPayload4Metasploit - Single payload loader class to
be used in the Metasploit project</title>
</head>
<body>
<h1>JavaPayload4Metasploit - Single payload loader class to be used
in the Metasploit project</h1>

<p><i>&copy; 2010 Michael 'mihi' Schierl, <tt>&lt;schierlm
at users dot sourceforge dot net&gt;</tt></i></p>

<h2>Introduction</h2>

<p>The <a href="http://schierlm.users.sourceforge.net/JavaPayload/">JavaPayload</a>s
contain useful payloads written in pure Java. But they assume that the
attacker has a Java VM on his machine, as the the builders and stage
handlers are written in Java. In addition, when creating a new payload
class that should reside in a signed jar, the jar has to be re-signed as
classes have changed.</p>

<p>In contrast, this package contains a single <i>metasploit.Payload</i>
class which is configured by a property file in the classpath (i. e. in
the same jar). As it is possible to add unsigned resources to a jar
without requiring to re-sign it, and as it is easy to manipulate zip/jar
files from Ruby, this makes it possible to leverage the powers of
JavaPayload from Metasploit which is written in Ruby and not in Java.</p>

<h2>System requirements</h2>

<p>Same as JavaPayload. JRE 1.2 on the victim machine is enough <tt>:-)</tt></p>

<p>On the attacker machine, no Java at all is required.</p>

<h2>How to use the <i>Payload</i> class.</h2>

<p>The <i>Payload</i> class is
a standard java main class (i. e. it has a <tt>public
static void main(String[])</tt> method), so the most obvious way to invoke it
is putting it into a Jar file whose manifest's <tt>Main-Class</tt>
attribute is <tt>metasploit.Payload</tt>. The resuling jar can be
started using <tt>java -jar jarfile.jar</tt>. There are 3 example jars
available that use this technique; they are described later.</p>

<p>Alternatively, the main class can of course be called from other
classes, like <tt>metasploit.Payload.main(null);</tt>, as the arguments
parameter is ignored. Note that in a sandboxed environment the caller
needs to have all permissions, and also the <i>Payload</i> class has to
be loaded with all permissions. In case there is untrusted code on the
stack trace (but the direct caller has all permissions), the call has to
be wrapped in a <a
	href="http://download.oracle.com/javase/1.4.2/docs/api/java/security/AccessController.html#doPrivileged(java.security.PrivilegedExceptionAction)">doPrivileged</a>
call (like it is done in the several well known public exploits for
CVE-2008-5353).</p>

<p>Once loaded, the class will lookup a file called <tt>/metasploit.dat</tt>
from the class path and load it as a <a
	href="http://download.oracle.com/javase/1.4.2/docs/api/java/util/Properties.html#load(java.io.InputStream)">Property
file</a> (basically a text file with <tt>Name=value</tt> lines, but note
that some special characters need escaping). If the file cannot be
found, default values are used.</p>

<p>Depending on the property values (see below), the class will then
optionally write itself to disk and spawn a sub-process (once or several
times) to disconnect the payload from the calling process. All temporary
files will be deleted afterwards. (Even on Windows it is possible to
delete a running class file as technically, not the class file but the
Java VM is running).</p>

<p>After that, it will either listen on a port and accept a socket,
connect to an URL (using a protocol like HTTP or HTTPS),
create an active socket connection, or (for debugging purposes) just
uses standard input and standard output; in any case, the resulting
input/output streams are used for the staging</p>

<p>Once the stage is loaded, the streams are handed to the stage.
Stages may require optional parameters (a string) which can be given
in the property file.</p>

<p>When the stage quits, the payload class terminates and cleans up
after itself if needed.</p>

<h2>Supported properties (and their default values)</h2>

<h3><tt>Spawn</tt>(<tt>=0</tt>)</h3>

<p>The number of java processes that should be spawned. <tt>0</tt>
will run the payload inside the original process, <tt>1</tt> will spawn
once (to continue running when the original process terminates), and <tt>2</tt>
will spawn twice (on certain popular operating systems it is impossible
to obtain parent process informaion if the parent process has already
died).</p>

<h3><tt>Executable</tt>(<tt>=</tt>)</h3>

<p>Points to an executable in the class path (next to
metasploit.dat), which will be extracted to a temporary directory (with
original filename), made executable (if needed by the OS) and executed.
When this option is present, no staging will be performed and all
options documented below are ignored.</p>

<h3><tt>StageParameters</tt>(<tt>=</tt>)</h3>

<p>Additional parameters to be used by the stage, regardless whether
it was embedded or not. Only few stages support/require parameters.</p>

<h3><tt>URL</tt>(<tt>=</tt>)</h3>

<p>Load the stage from this URL. The URL will be requested and the 
resulting stream will be used for loading the stage classes from.
As the stage's output stream will discard all input, this is only
useful with stages (like Meterpreter) that can communicate via
some other means back to the attacker.</p>

<p><b>Note: </b>If this option is given, LHOST and LPORT are ignored.</p>

<h3><tt>LPORT</tt>(<tt>=4444</tt>)</h3>

<p>Port to listen on or to connect to (if <tt>LHOST</tt> is also
set). If explicitly set to <tt>0</tt>, no connection will be made, but
standard input/output streams will be used instead.</p>

<h3><tt>LHOST</tt>(<tt>=<a></a></tt>)</h3>

<p>Host to connect to. If not set, the payload will listen instead.</p>

<h2>Staging protocol</h2>

<p>The staging protocol is quite simple. All classes are sent
uncompressed (as they are inside the .jar file). Each class is prefixed
by a 32-bit big-endian size. After the last class, a size of 0 is sent.
The classes will be defined in the order they are sent (i. e. they can
only refer to classes defined before), and the last sent class will be
loaded as a stage.</p>

<p>In case of an embedded stage, no staging is used - the stream is
directly passed to the stage.</p>

<h2>Supported stages (in alphabetical order)</h2>

<p>The stages are original <a
	href="http://schierlm.users.sourceforge.net/JavaPayload/">JavaPayload</a>
stages to make updates easier. All stages listed here can be used
without special "Java" tricks (like serialization or JDWP protocol), to
easily use them from Ruby.</p>

<h3><tt>Meterpreter</tt></h3>
<dl>
	<dt><b>Stage classes</b></dt>
	<dd>javapayload.stage.Stage,
	com.metasploit.meterpreter.MemoryBufferURLConnection,
	com.metasploit.meterpreter.MemoryBufferURLStreamHandler,
	javapayload.stage.Meterpreter</dd>
</dl>
<dl>
	<dt><b>Parameters</b></dt>
	<dd>Optional parameter <tt>NoRedirect</tt> for debugging.</dd>
</dl>
<dl>
	<dt><b>Stage protocol</b></dt>
	<dd>Meterpreter protocol</dd>
</dl>

<p>Loader to load the Java version of Metasploit's own
post-exploitation toolkit.</p>

<h3><tt>Shell</tt></h3>
<dl>
	<dt><b>Stage classes</b></dt>
	<dd>javapayload.stage.Stage, javapayload.stage.StreamForwarder,
	javapayload.stage.Shell</dd>
</dl>
<dl>
	<dt><b>Parameters</b></dt>
	<dd>Not supported</dd>
</dl>
<dl>
	<dt><b>Stage protocol</b></dt>
	<dd>Plain text</dd>
</dl>

<p>This stager loads /bin/sh on Unix systems and cmd.exe on Windows
systems, and else just behaves like the <tt>Exec</tt> stage.</p>

</body>
</html>